🔗 Contact Plan Generator

Tool to schedule contacts for each satellite in a constellation

This guide is for CPG V2 which uses rabbit queue cpg-v2. CPG V1 is deprecated and new missions should not be configured to use it.

🔗 Config Format

{
  cpg_queue: <rabbit queue mission planner will send this request to>,
  num_days_sched_out: <number of periods to schedule>,
  sat_nums: [
      {
          <sat number>: <name of mode to use>
      }   
  ],
  scoring_method: <weights or filters>,
  scoring_weights: {
      <criteria>: <weight to use for this criteria, total must be 1>
  },
  filter_criteria: <ordered list of criteria to use in filters mode, described below>,
  sites: { 
      <site name>: {
          min_maxel: <minimum maximum elevation for contacts at this site>,
          turnover_time_seconds: <minimum time between subsequent contacts on the same antenna at this site>
      }
  },
  antennas: {  
     <antenna name>: {
         minel: < Only used by V1. Minimum elevation for contacts at this antenna>
     }
  },
  modes: {
    <mode name>: <mode configuration, described below>
  },
  split_passes_longer_than: <split visibility windows more than this many minutes long into multiple>,
  split_into_duration: <split long visibility windows, as defined by split_passes_longer_than, into visibility windows of this many minutes length>,
  split_into_number: <split long visibility windows into this many visibility windows>,
  period: <Length of period to use for contacts/period etc. in hours>,
  min_contact_duration_per_period: <global setting for minimum number of contact minutes/period/sat, overridden by mode setting if present>,
  max_contact_duration_per_period: <global setting for maximum number of contact minutes/period/sat, overridden by mode setting if present>,
  min_contacts_per_period: <global setting for minimum number of contacts/period/sat, overridden by mode setting if present>,
  max_contacts_per_period: <global setting for maximum number of contacts/period/sat, overridden by mode setting if present>,
  max_scheduled_duration: <maximum length of contact to schedule in minutes>,
  default_goal_duration: <global setting to use as goal contact length in minutes when scoring using the contact_duration weight, overridden by mode setting if present>,
  site_preferences: <list of site names, used when filtering on site in filters mode>,
  delete_cpg_scheduled: <if true cpg will delete previously cpg scheduled contacts that are not in this contact plan. Default is to leave them>,
  mark_not_cpg_scheduled: <if true contacts scheduled in this plan will be marked as not cpg scheduled>,
  count_manually_scheduled_toward_max: <(default false) when true manually scheduled contacts are counted toward max contact counts and durations>,
  min_passes_to_consider: <(default 50) stop attempting to generate schedules and return the best yet seen when this many passes remain to consider>,
  change_buffer_hours: <if set only changes due to TLE shifts will be made within this many hours of now>,
  min_contact_duration_per_period: <Only used by V1. Global setting for minimum number of contact minutes/period/sat, overridden by mode setting if present>,
  max_contact_duration_per_period: <Only used by V1. Global setting for maximum number of contact minutes/period/sat, overridden by mode setting if present>,
  min_contacts_per_period: <Only used by V1. Global setting for minimum number of contacts/period/sat, overridden by mode setting if present>,
  max_contacts_per_period: <Only used by V1. Global setting for maximum number of contacts/period/sat, overridden by mode setting if present>,
  default_goal_duration: <Only used by V1. Global setting to use as goal contact length in minutes when scoring using the contact_duration weight, overridden by mode setting if present>,
  contact_duration_coefficient: <Only used by V1. Used when scoring schedules on contact duration in weights mode. Omit to use default (recommended)>,
  contact_gap_coefficient: <Only used by V1. Used when scoring schedules on contact gap in weights mode. Omit to use default (recommended)>,
  period_execution_time: <Only used by V1. Limit on amount of time to use allow to schedule each period in seconds>,
  generate_function: <Only used by V1. Specifies the function to use to generate contact plans.>
}

🔗 Weights Mode

Scores each contact according to the weights below. The total of all weights must be 1. Constructs a contact plan by repeatedly adding the highest scoring contact not yet scheduled to the plan. If no plan meeting all criteria is found the best plan yet seen is saved and the process restarts with a different initial choice of contact. The best plan seen will be returned if no plan meeting all criteria is found.

Supported weights:

contact_duration: Scores contacts on how close the total AOS to LOS time is to goal_contact_duration in the mode that sat is using or default_goal_duration if no goal_contact_minutes_per_period is provided.
contact_gap: Scores contacts on how close the gap to the previous contact is to goal_contact_gap for each sat in the mode it is using.
contact_site: Scores contacts on which site they occur at according to site_preferences in the mode for each sat
time_of_day: Score contacts on when during the day contacts occur according to time_weights in the mode for each sat
maxEl: Scores contacts on maxel

The following are only supported by V1.

contact_count: Scores schedules on how close the number of contacts for each period for each sat is to goal_contacts_per_period in the mode that sat is using.
evenness: Scores schedules on how evenly contact counts are split between sats

🔗 Filters Mode

In filters mode cpg will start with a contact plan containing all possible contacts and proceed through the filter_criteria list at each stage filtering out contacts that do not meet the criteria. If no schedules meet a criterion or there are multiple schedules after filtering on all criteria cpg will attempt to choose one in a logical way.

Supported criteria:

sites: Filters contacts on which site they occur at using site_preference
time_of_day: Filters contacts on when during the day they occur according to preferred_times_of_day in the mode of each sat
contact_gap: Filters contacts on gap between contacts using contact_gap_preference.
maxEl: Filters contacts on maxEl using max_el_preference.
contact_duration: Filters contacts on duration using contact_duration_preference.

The following are only supported by V1.

contact_count: Filters schedules on contact count according to contact_count_preference in the mode for each sat. 0, 1, and 2 number lists can be used in different modes. If there any mode in use contains anything other than a 2 number list a single schedule will be returned after this stage.
contact_minutes_per_period: Filters schedules on contact minutes/period using contact_minutes_per_period_preference. As for contact_count_preference,this can be a list of 2, 1, or 0 numbers which will be treated as a range to filter within, a goal to choose the schedule closest to, or will cause cpg to maximize contact minutes, respectively.

🔗 Mode Configuration

{
  min_daily_aos: <earliest AOS for a sat using this mode>,
  max_daily_aos: <latest AOS for a sat using this mode>,
  sites: <list of site names to use or "all">,
  min_contact_gap_minutes: <minimum number of minutes between subsequent contacts for a sat using this mode (LOS to AOS)>,
  min_contact_duration_minutes: <minimum length of a contact in minutes>,
  max_contact_duration_minutes: <maximum length of a contact in minutes>,
  min_period_contacts: <minimum number of contacts/period for a sat using this mode>,
  min_daily_minutes: <minimum total contact duration/period in minutes for a sat using this mode>,
  max_daily_minutes: <maximum total contact duration/period in minutes for a sat using this mode>,
  max_period_contacts: <maximum number of contacts/period for a sat using this mode>,
  min_max_el: <minimum maxEl of contacts for a sat using this mode>,
  antennas: <list of antenna names sats using this mode can use. List is in preference order. If this is omitted, all antennas are allowed and no preference is applied>,
  simultaneous_contacts: <boolean controlling whether sats using this mode can have a contact at the same time as another sat in the constellation>,
  goal_contact_gap: <desired number of minutes between contacts for a sat using this mode. Used for contact_gap in weights and filters modes>,
  site_preferences: [
    {
      name: <site name>
      weights: <weight to assign this site when scoring, higher will be preferred>
    }
  ],
  time_weights: [
    {
      start: <start time>,
      end: <end time>,
      weight: <weight to use when scoring, higher will be preferred>
    }
  ],
  preferred_times_of_day: [{start: <start time>, end: <end time>}],
  periodic_pointing: <Only used by V1. Should be omitted or equivalently false in general. Only used for GNOMES-3>,
  goal_contacts_per_period: <Only used by V1. Desired number of contacts/period for a sat using this mode. Used for contact_count in weights mode>,
  goal_contact_minutes_per_period: <Only used by V1. Desired total contact minutes/period for a sat using this mode. Used for contact_duration in weights mode>,
  contact_count_preference: <Only used by V1. Can be a list of 0, 1 or 2 numbers. If one number cpg will return the schedule in which all sats have the closest to the number of contacts/period in the mode they are using. If two numbers cpg will filter out all schedules with contact counts outside the range for at least one period. If omitted or empty cpg will return the schedule maximimizing contact counts.>
  contact_minutes_per_period_preference: <Only used by V1. Similar to contact_count_preference, but considering total contact time instead of count>,
  contact_gap_preference: <Only used by V1. Similar to contact_count_preference, but considering gap between contacts for this sat instead of contact count>
  max_el_preference: <Only used by V1. Similar to contact_count_preference, but considering maxEl instead of contact count>,
  contact_duration_preference: <Only used by V1. Similar to contact_count_preference, but considering contact duration instead of contact count>
}

Times of day, such as min_daily_aos should be in the format hh:mm:ssZ.

🔗 Example Configs

This config uses filters mode to choose schedules with high contact counts and contact gaps close to 1 hour.

{
  "cpg_queue": "cpg",
  "num_days_sched_out": 5,
  "scoring_method": "filters",
  "filter_criteria": ["contact_gap"],
  "sat_nums": [
    {
      "1": "priority"
    },
    {
      "2": "default"
    },
    {
      "3": "default"
    },
    {
      "4": "default"
    }
  ],
  "sites": {
    "AWARUA": {
      "min_maxel": 0.174533,
      "turnover_time_seconds": 60
    },
    "SVALSAT": {
      "min_maxel": 0.174533,
      "turnover_time_seconds": 60
    }
  },
  "modes": {
    "priority": {
      "simultaneous_contacts": false,
      "min_contact_gap_minutes": 1,
      "min_contact_duration_minutes": 5,
      "min_daily_aos": "15:00:00Z",
      "max_daily_aos": "23:59:59Z",
      "sites": [
        "SVALSAT"
      ],
      "goal_contact_gap": 60
    },
    "default": {
      "simultaneous_contacts": false,
      "min_contact_gap_minutes": 1,
      "min_contact_duration_minutes": 5,
      "min_daily_aos": "00:00:00Z",
      "max_daily_aos": "14:59:59Z",
      "sites": "all",
      "min_daily_minutes": 15,
      "goal_contact_gap": 60
    }
  }
}

This config only allows certain antennas for each sat and chooses contacts based on duration and gap using weights mode.

{
  "cpg_queue": "cpg",
  "num_days_sched_out": 3,
  "scoring_method": "weights",
  "scoring_weights": {
    "contact_duration": .5,
    "contact_gap": .5
  },
  "sat_nums": [
    {
      "1": "default"
    },
    {
      "2": "custom"
    }
  ],
  "sites": {
    "TROLL": {
      "min_maxel": 0.174533,
      "turnover_time_seconds": 60
    },
    "SVALSAT": {
      "min_maxel": 0.174533,
      "turnover_time_seconds": 60
    }
  },
  "modes": {
    "default": {
      "antennas": [
        "SG180",
        "SG182"
        ]
      "simultaneous_contacts": true,
      "min_contact_gap_minutes": 10,
      "goal_contact_gap": 360,
      "max_contact_duration_minutes": 5,
      "min_contact_duration_minutes": 4.5,
      "sites": "all"
    },
    "custom": {
      "antennas": [
        "SG140",
        "TR4"
      ],
      "simultaneous_contacts": true,
      "min_contact_gap_minutes": 10,
      "goal_contact_gap": 360,
      "min_contact_duration_minutes": 2,
      "sites": "all",
      "min_max_el": 0.20944
    }
  }
}